package com.kexio.enterprise.governance.ratelimit.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import com.kexio.enterprise.governance.ratelimit.enums.RateLimitAlgorithm;

/**
 * 限流注解
 * 
 * 用于标记需要限流的方法
 * 
 * 使用示例：
 * <pre>
 * &#64;RateLimit(key = "user_login", rate = 5, per = 60)
 * public Result login(LoginRequest request) {
 *     // 登录逻辑
 * }
 * 
 * &#64;RateLimit(
 *     key = "api_call", 
 *     rate = 100, 
 *     per = 60,
 *     algorithm = RateLimitAlgorithm.SLIDING_WINDOW
 * )
 * public Result apiCall() {
 *     // API调用逻辑
 * }
 * </pre>
 * 
 * @author Kexio
 * @since 1.0.0
 */
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
public @interface RateLimit {

    /**
     * 限流键
     * 用于标识不同的限流规则
     */
    String key();

    /**
     * 限流次数
     * 在指定时间窗口内允许的最大请求数
     */
    int rate();

    /**
     * 时间窗口（秒）
     * 限流统计的时间窗口大小
     */
    int per() default 60;

    /**
     * 限流算法
     */
    RateLimitAlgorithm algorithm() default RateLimitAlgorithm.TOKEN_BUCKET;

    /**
     * 限流描述
     * 用于日志记录和监控
     */
    String description() default "";

    /**
     * 是否启用限流
     * 可以通过配置动态开关
     */
    boolean enabled() default true;

    /**
     * 限流失败时的错误消息
     */
    String errorMessage() default "访问频率过高，请稍后再试";

    /**
     * 限流失败时的HTTP状态码
     */
    int errorCode() default 429;

    /**
     * 是否包含用户ID在限流键中
     * true: key + userId, false: 仅使用key
     */
    boolean includeUserId() default false;

    /**
     * 是否包含IP地址在限流键中
     */
    boolean includeClientIp() default false;

    /**
     * 自定义限流键表达式
     * 支持SpEL表达式，如: "#{request.userId}_#{request.action}"
     */
    String keyExpression() default "";

    /**
     * 限流条件
     * 满足条件时才进行限流检查，支持SpEL表达式
     */
    String condition() default "";

    /**
     * 限流范围
     */
    RateLimitScope scope() default RateLimitScope.GLOBAL;

    /**
     * 降级策略
     * 限流触发时的处理方式
     */
    FallbackStrategy fallbackStrategy() default FallbackStrategy.EXCEPTION;

    /**
     * 限流范围枚举
     */
    enum RateLimitScope {
        /**
         * 全局限流
         */
        GLOBAL,
        
        /**
         * 用户级别限流
         */
        USER,
        
        /**
         * IP级别限流
         */
        IP,
        
        /**
         * 自定义限流
         */
        CUSTOM
    }

    /**
     * 降级策略枚举
     */
    enum FallbackStrategy {
        /**
         * 抛出异常
         */
        EXCEPTION,
        
        /**
         * 返回默认值
         */
        DEFAULT_VALUE,
        
        /**
         * 调用降级方法
         */
        FALLBACK_METHOD,
        
        /**
         * 忽略（跳过限流检查）
         */
        IGNORE
    }
}
